Private Repositories

Note

Some Git hosters - notably GitLab and possibly on-premise GitLab instances as well - require you to specify the .git suffix in the repository URL, otherwise they will send a HTTP 301 redirect to the repository URL suffixed with .git. ArgoCD will not follow these redirects, so you have to adapt your repository URL to be suffixed with .git.

Credentials

If application manifests are located in private repository then repository credentials have to be configured. Argo CD supports both HTTPS and SSH Git credentials.

HTTPS Username And Password Credential

Private repositories that require a username and password typically have a URL that start with https:// rather than git@ or ssh://.

Credentials can be configured using Argo CD CLI:

  1. argocd repo add https://github.com/argoproj/argocd-example-apps --username <username> --password <password>

or UI:

v1.2 or later

  1. Navigate to Settings/Repositories

    connect repo overview

  2. Click Connect Repo using HTTPS button and enter credentials

    connect repo

    Note: username in screenshot is for illustration purposes only , we have no relationship to this GitHub account should it exist.

  3. Click Connect to test the connection and have the repository added

earlier than v1.2

  1. Navigate to Settings/Repositories
  2. Click Connect Repo button and enter HTTPS credentials

connect repo

Access Token

Instead of using username and password you might use access token. Following instructions of your Git hosting service to generate the token:

Then, connect the repository using any non-empty string as username and the access token value as a password.

Note

For some services, you might have to specify your account name as the username instead of any string.

TLS Client Certificates for HTTPS repositories

v1.2 and later

If your repository server requires you to use TLS client certificates for authentication, you can configure ArgoCD repositories to make use of them. For this purpose, --tls-client-cert-path and --tls-client-cert-key-path switches to the argocd repo add command can be used to specify the files on your local system containing client certificate and the corresponding key, respectively:

  1. argocd repo add https://repo.example.com/repo.git --tls-client-cert-path ~/mycert.crt --tls-client-cert-key-path ~/mycert.key

Of course, you can also use this in combination with the --username and --password switches, if your repository server should require this. The options --tls-client-cert-path and --tls-client-cert-key-path must always be specified together.

Your TLS client certificate and corresponding key can also be configured using the UI, see instructions for adding Git repos using HTTPS.

Note

Your client certificate and key data must be in PEM format, other formats (such as PKCS12) are not understood. Also make sure that your certificate’s key is not password protected, otherwise it cannot be used by ArgoCD.

Note

When pasting TLS client certificate and key in the text areas in the web UI, make sure they contain no unintended line breaks or additional characters.

SSH Private Key Credential

Private repositories that require an SSH private key have a URL that typically start with git@ or ssh:// rather than https://.

v1.2 or later

You can configure your Git repository using HTTPS either using the CLI or the UI.

Using the CLI:

  1. argocd repo add git@github.com:argoproj/argocd-example-apps.git --ssh-private-key-path ~/.ssh/id_rsa

Using the UI:

  1. Navigate to Settings/Repositories

    connect repo overview

  2. Click Connect Repo using SSH button, enter the URL and paste the SSH private key

    connect repo

  3. Click Connect to test the connection and have the repository added

Note

When pasting SSH private key in the UI, make sure there are no unintended line breaks or additional characters in the text area

Note

When your SSH repository is served from a non-standard port, you have to use ssh://-style URLs to specify your repository. The scp-style git@yourgit.com:yourrepo URLs do not support port specification, and will treat any port number as part of the repository’s path.

earlier than v1.2

The Argo CD UI don’t support configuring SSH credentials. The SSH credentials can only be configured using the Argo CD CLI:

  1. argocd repo add git@github.com:argoproj/argocd-example-apps.git --ssh-private-key-path ~/.ssh/id_rsa

GitHub App Credential

Private repositories that are hosted on GitHub.com or GitHub Enterprise can be accessed using credentials from a GitHub Application. Consult the GitHub documentation on how to create an application.

Note

Ensure your application has at least Read-only permissions to the Contents of the repository. This is the minimum requirement.

previous to v1.9

GitHub App credentials are not supported.

v1.9 or later

You can configure access to your Git repository hosted by GitHub.com or GitHub Enterprise using the GitHub App method by either using the CLI or the UI.

Using the CLI:

  1. argocd repo add https://github.com/argoproj/argocd-example-apps.git --github-app-id 1 --github-app-installation-id 2 --github-app-private-key-path test.private-key.pem

Using the UI:

  1. Navigate to Settings/Repositories

connect repo overview

  1. Click Connect Repo using GitHub App button, enter the URL, App Id, Installation Id, and the app’s private key.

connect repo

  1. Click Connect to test the connection and have the repository added

Note

When pasting GitHub App private key in the UI, make sure there are no unintended line breaks or additional characters in the text area

Credential templates

previous to v1.4

Credential templates are available only via declarative setup, see Repository credentials in Operator Manual.

v1.4 and later

You can also set up credentials to serve as templates for connecting repositories, without having to repeat credential configuration. For example, if you setup credential templates for the URL prefix https://github.com/argoproj, these credentials will be used for all repositories with this URL as prefix (e.g. https://github.com/argoproj/argocd-example-apps) that do not have their own credentials configured.

To set up a credential template using the Web UI, simply fill in all relevant credential information in the Connect repo using SSH or Connect repo using HTTPS dialogues (as described above), but select Save as credential template instead of Connect to save the credential template. Be sure to only enter the prefix URL (i.e. https://github.com/argoproj) instead of the complete repository URL (i.e. https://github.com/argoproj/argocd-example-apps) in the field Repository URL

To manage credential templates using the CLI, use the repocreds sub-command, for example argocd repocreds add https://github.com/argoproj --username youruser --password yourpass would setup a credential template for the URL prefix https://github.com/argoproj using the specified username/password combination. Similar to the repo sub-command, you can also list and remove repository credentials using the argocd repocreds list and argocd repocreds rm commands, respectively.

In order for ArgoCD to use a credential template for any given repository, the following conditions must be met:

  • The repository must either not be configured at all, or if configured, must not contain any credential information
  • The URL configured for a credential template (e.g. https://github.com/argoproj) must match as prefix for the repository URL (e.g. https://github.com/argoproj/argocd-example-apps).

Note

Repositories that require authentication can be added using CLI or Web UI without specifying credentials only after a matching repository credential has been set up

Note

Matching credential template URL prefixes is done on a best match effort, so the longest (best) match will take precedence. The order of definition is not important, as opposed to pre v1.4 configuration.

The following is an example CLI session, depicting repository credential set-up:

  1. # Try to add a private repository without specifying credentials, will fail
  2. $ argocd repo add https://docker-build/repos/argocd-example-apps
  3. FATA[0000] rpc error: code = Unknown desc = authentication required 
  5. # Setup a credential template for all repos under https://docker-build/repos
  6. $ argocd repocreds add https://docker-build/repos --username test --password test
  7. repository credentials for 'https://docker-build/repos' added
  9. # Repeat first step, add repo without specifying credentials
  10. # URL for template matches, will succeed
  11. $ argocd repo add https://docker-build/repos/argocd-example-apps
  12. repository 'https://docker-build/repos/argocd-example-apps' added
  14. # Add another repo under https://docker-build/repos, specifying invalid creds
  15. # Will fail, because it will not use the template (has own creds)
  16. $ argocd repo add https://docker-build/repos/example-apps-part-two --username test --password invalid
  17. FATA[0000] rpc error: code = Unknown desc = authentication required

Self-signed & Untrusted TLS Certificates

v1.2 or later

If you are connecting a repository on a HTTPS server using a self-signed certificate, or a certificate signed by a custom Certificate Authority (CA) which are not known to ArgoCD, the repository will not be added due to security reasons. This is indicated by an error message such as x509: certificate signed by unknown authority.

  1. You can let ArgoCD connect the repository in an insecure way, without verifying the server’s certificate at all. This can be accomplished by using the --insecure-skip-server-verification flag when adding the repository with the argocd CLI utility. However, this should be done only for non-production setups, as it imposes a serious security issue through possible man-in-the-middle attacks.

  2. You can configure ArgoCD to use a custom certificate for the verification of the server’s certificate using the cert add-tls command of the argocd CLI utility. This is the recommended method and suitable for production use. In order to do so, you will need the server’s certificate, or the certificate of the CA used to sign the server’s certificate, in PEM format.

Note

For invalid server certificates, such as those without matching server name, or those that are expired, adding a CA certificate will not help. In this case, your only option will be to use the --insecure-skip-server-verification flag to connect the repository. You are strongly urged to use a valid certificate on the repository server, or to urge the server’s administrator to replace the faulty certificate with a valid one.

Note

TLS certificates are configured on a per-server, not on a per-repository basis. If you connect multiple repositories from the same server, you only have to configure the certificates once for this server.

Note

It can take up to a couple of minutes until the changes performed by the argocd cert command are propagated across your cluster, depending on your Kubernetes setup.

Managing TLS certificates using the CLI

You can list all configured TLS certificates by using the argocd cert list command using the --cert-type https modifier:

  1. $ argocd cert list --cert-type https
  2. HOSTNAME      TYPE   SUBTYPE  FINGERPRINT/SUBJECT
  3. docker-build  https  rsa      CN=ArgoCD Test CA
  4. localhost     https  rsa      CN=localhost

Example for adding a HTTPS repository to ArgoCD without verifying the server’s certificate (Caution: This is not recommended for production use):

  1. argocd repo add --insecure-skip-server-verification https://git.example.com/test-repo

Example for adding a CA certificate contained in file ~/myca-cert.pem to properly verify the repository server:

  1. argocd cert add-tls git.example.com --from ~/myca-cert.pem
  2. argocd repo add https://git.example.com/test-repo

You can also add more than one PEM for a server by concatenating them into the input stream. This might be useful if the repository server is about to replace the server certificate, possibly with one signed by a different CA. This way, you can have the old (current) as well as the new (future) certificate co-existing. If you already have the old certificate configured, use the --upsert flag and add the old and the new one in a single run:

  1. cat cert1.pem cert2.pem | argocd cert add-tls git.example.com --upsert

Note

To replace an existing certificate for a server, use the --upsert flag to the cert add-tls CLI command.

Finally, TLS certificates can be removed using the argocd cert rm command with the --cert-type https modifier:

  1. argocd cert rm --cert-type https localhost

Managing TLS certificates using the ArgoCD web UI

It is possible to add and remove TLS certificates using the ArgoCD web UI:

  1. In the navigation pane to the left, click on “Settings” and choose “Certificates” from the settings menu

  2. The following page lists all currently configured certificates and provides you with the option to add either a new TLS certificate or SSH known entries:

    manage certificates

  3. Click on “Add TLS certificate”, fill in relevant data and click on “Create”. Take care to specify only the FQDN of your repository server (not the URL) and that you C&P the complete PEM of your TLS certificate into the text area field, including the ----BEGIN CERTIFICATE---- and ----END CERTIFICATE---- lines:

    add tls certificate

  4. To remove a certificate, click on the small three-dotted button next to the certificate entry, select “Remove” from the pop-up menu and confirm the removal in the following dialogue.

    remove certificate

Managing TLS certificates using declarative configuration

You can also manage TLS certificates in a declarative, self-managed ArgoCD setup. All TLS certificates are stored in the ConfigMap object argocd-tls-cert-cm. Please refer to the Operator Manual for more information.

Before v1.2

We do not currently have first-class support for this. See #1513.

As a work-around, you can customize your Argo CD image. See #1344

Unknown SSH Hosts

If you are using a privately hosted Git service over SSH, then you have the following options:

v1.2 or later

  1. You can let ArgoCD connect the repository in an insecure way, without verifying the server’s SSH host key at all. This can be accomplished by using the --insecure-skip-server-verification flag when adding the repository with the argocd CLI utility. However, this should be done only for non-production setups, as it imposes a serious security issue through possible man-in-the-middle attacks.

  2. You can make the server’s SSH public key known to ArgoCD by using the cert add-ssh command of the argocd CLI utility. This is the recommended method and suitable for production use. In order to do so, you will need the server’s SSH public host key, in the known_hosts format understood by ssh. You can get the server’s public SSH host key e.g. by using the ssh-keyscan utility.

Note

It can take up to a couple of minutes until the changes performed by the argocd cert command are propagated across your cluster, depending on your Kubernetes setup.

Note

When importing SSH known hosts key from a known_hosts file, the hostnames or IP addresses in the input data must not be hashed. If your known_hosts file contains hashed entries, it cannot be used as input source for adding SSH known hosts - neither in the CLI nor in the UI. If you absolutely wish to use hashed known hosts data, the only option will be using declarative setup (see below). Be aware that this will break CLI and UI certificate management, so it is generally not recommended.

Managing SSH Known Hosts using the CLI

You can list all configured SSH known host entries using the argocd cert list command with the --cert-type ssh modifier:

  1. $ argocd cert list --cert-type ssh
  2. HOSTNAME                 TYPE  SUBTYPE              FINGERPRINT/SUBJECT
  3. bitbucket.org            ssh   ssh-rsa              SHA256:zzXQOXSRBEiUtuE8AikJYKwbHaxvSc0ojez9YXaGp1A
  4. github.com               ssh   ssh-rsa              SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8
  5. gitlab.com               ssh   ecdsa-sha2-nistp256  SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw
  6. gitlab.com               ssh   ssh-ed25519          SHA256:eUXGGm1YGsMAS7vkcx6JOJdOGHPem5gQp4taiCfCLB8
  7. gitlab.com               ssh   ssh-rsa              SHA256:ROQFvPThGrW4RuWLoL9tq9I9zJ42fK4XywyRtbOz/EQ
  8. ssh.dev.azure.com        ssh   ssh-rsa              SHA256:ohD8VZEXGWo6Ez8GSEJQ9WpafgLFsOfLOtGGQCQo6Og
  9. vs-ssh.visualstudio.com  ssh   ssh-rsa              SHA256:ohD8VZEXGWo6Ez8GSEJQ9WpafgLFsOfLOtGGQCQo6Og

For adding SSH known host entries, the argocd cert add-ssh command can be used. You can either add from a file (using the --from <file> modifier), or by reading stdin when the --batch modifier was specified. In both cases, input must be in known_hosts format as understood by the OpenSSH client.

Example for adding all available SSH public host keys for a server to ArgoCD, as collected by ssh-keyscan:

  1. ssh-keyscan server.example.com | argocd cert add-ssh --batch

Example for importing an existing known_hosts file to ArgoCD:

  1. argocd cert add-ssh --batch --from /etc/ssh/ssh_known_hosts

Finally, SSH known host entries can be removed using the argocd cert rm command with the --cert-type ssh modifier:

  1. argocd cert rm bitbucket.org --cert-type ssh

If you have multiple SSH known host entries for a given host with different key sub-types (e.g. as for gitlab.com in the example above, there are keys of sub-types ssh-rsa, ssh-ed25519 and ecdsa-sha2-nistp256) and you want to only remove one of them, you can further narrow down the selection using the --cert-sub-type modifier:

  1. argocd cert rm gitlab.com --cert-type ssh --cert-sub-type ssh-ed25519

Managing SSH known hosts data using the ArgoCD web UI

It is possible to add and remove SSH known hosts entries using the ArgoCD web UI:

  1. In the navigation pane to the left, click on “Settings” and choose “Certificates” from the settings menu

  2. The following page lists all currently configured certificates and provides you with the option to add either a new TLS certificate or SSH known entries:

    manage certificates

  3. Click on “Add SSH known hosts” and paste your SSH known hosts data in the following mask. Important: Make sure there are no line breaks in the entries (key data) when you paste the data. Afterwards, click on “Create”.

    manage ssh known hosts

  4. To remove a certificate, click on the small three-dotted button next to the certificate entry, select “Remove” from the pop-up menu and confirm the removal in the following dialogue.

    remove certificate

Managing SSH known hosts data using declarative setup

You can also manage SSH known hosts entries in a declarative, self-managed ArgoCD setup. All SSH public host keys are stored in the ConfigMap object argocd-ssh-known-hosts-cm. For more details, please refer to the Operator Manual

Before v1.2

(1) You can customize the Argo CD Docker image by adding the host’s SSH public key to /etc/ssh/ssh_known_hosts. Additional entries to this file can be generated using the ssh-keyscan utility (e.g. ssh-keyscan your-private-git-server.com. For more information see example which demonstrates how /etc/ssh/ssh_known_hosts can be customized.

Note

The /etc/ssh/ssh_known_hosts should include Git host on each Argo CD deployment as well as on a computer where argocd repo add is executed. After resolving issue #1514 only argocd-repo-server deployment has to be customized.

(1) Add repository using Argo CD CLI and --insecure-ignore-host-key flag:

  1. argocd repo add git@github.com:argoproj/argocd-example-apps.git --ssh-private-key-path ~/.ssh/id_rsa --insecure-ignore-host-key

Don’t use in production

The --insecure-ignore-host-key should not be used in production as this is subject to man-in-the-middle attacks.

This does not work for Kustomize remote bases or custom plugins

For Kustomize support, see #827.

Git Submodules

v1.4 or later

Submodules are supported and will be picked up automatically. If the submodule repository requires authentication then the credentials will need to match the credentials of the parent repository. Set ARGOCD_GIT_MODULES_ENABLED=false to disable submodule support

Declarative Configuration

See declarative setup